Managing Roles and Permissions

AccountRole accountRole = AccountRoleBuilder.newAccountRole()
	.withName("Regional Manager")
	.withPermissions(Arrays.asList("transaction.transaction", "transaction.in_person"))
	.withDescription("Customized Role for Regional Manager")
	.withEnabled(true)
	.build();
eslClient.getAccountService().addAccountRole(accountRole);

AccountRole accountRole = eslClient.getAccountService().getAccountRole("account_role_id");

List<AccountRole> accountRoles = eslClient.getAccountService().getAccountRoles();

AccountRole accountRole = eslClient.getAccountService().getAccountRole("account_role_id");
accountRole.setDescription("Updated Description");
accountRole.getPermissions().addAll(Arrays.asList("sender_admin.security_settings","sender_admin.reports"));
eslClient.getAccountService().updateAccountRole("account_role_id", accountRole);

AccountRole accountRole = eslClient.getAccountService().getAccountRole("account_role_id");
accountRole.setEnabled(false);
eslClient.getAccountService().updateAccountRole("account_role_id", accountRole);

eslClient.getAccountService().deleteAccountRole("account_role_id");

List<String> accountRoleUsers = client.getAccountService().getAccountRoleUsers("account_role_id");

List<AccountRole> acountRoles = new ArrayList<>();
acountRoles.add(AccountRoleBuilder.newAccountRole().withId("your_account_role_id1").build());
acountRoles.add(AccountRoleBuilder.newAccountRole().withId("your_account_role_id2").build());
acountRoles.add(AccountRoleBuilder.newAccountRole().withId("your_account_role_id3").build());
UserAccountRole userAccountRole = new UserAccountRole("sender_id","accountId",acountRoles);
userAccountRole = client.getAccountService().assignAccountRoleToUser(userAccountRole.getUserId(),
userAccountRole);

To download the full code sample see our Code Share site.

With the Roles and Permissions feature, admins have more control over their senders’ access permissions. By creating a customized Account Role with a set of permissions and assigning the role to a sender, it determines the actions available to the sender and makes it easy to manage the access rights of a large number of senders without having to change their respective permissions.

Without turning on the Roles and Permissions feature, admins are only able to specify two static role types: “Sender” and “Manager”. This may be insufficient when the number of senders grows and they need access to different elements in the account. Assigning roles and permissions to your senders allows you to control this.

Turn on roles and permissions

By default, the Roles and Permissions feature is disabled, so admins should contact our Support Team to arrange this configuration in the account. Once enabled, the option to configure Roles will appear in the OneSpan Sign Admin menu. For more information, see Managing Roles.

When making API calls with an API Key, OneSpan Sign creates an API Key session if one is not already in use. If an API Key session has already been created, then OneSpan Sign will use the existing session. However, if Roles and Permissions have been cached in this session then any changes that are made will not appear until the session expires. By default, API Key sessions expire after 15 minutes.

Available permissions

With a role-based access model, you can group senders with similar needs into a role. You then grant permissions to the role which determine the pages and actions the senders can access. The following table describes all of the permissions in OneSpan Sign. Note that each permission has a Permission ID which you will use when setting up the roles and permissions for your organization.

If a specific feature is not enabled for an account then the permission associated to that feature is not available. Also, the available permissions may change when new features and releases are rolled out to an account.

When creating custom roles via integration, you must ensure to include the template permission as well and not depend on the existing "Transaction" permission to determine whether templates are allowed to be created/updated/deleted.

Permission	Permission ID	Description
Trust Vault Permissions
No access		This permission denies access to the Trust Vault.
View their own transactions		This permission enables a Sender to view any of their transactions that have been archived to the Trust Vault.
View and delete their own transactions		This permission enables a Sender to view and delete any of their transactions that have been archived to the Trust Vault.
View all transactions		This permission enables a Sender to view all transactions that have been archived to the Trust Vault.
View and delete all transactions		This permission enables a Sender to view and delete all transactions that have been archived to the Trust Vault.
Sender Admin Permissions
Custom Fields	sender_admin.custom_fields	This permission enables a Sender to create and manage Custom Fields.
User Management	sender_admin.users	This permission enables a Sender to manage the users associated with their account.
Subscription account billing details	sender_admin.subscription	This permission enables a Sender to view the Subscription page, which contains billing details for their account.
API Access	sender_admin.api_access	This permission enables a Sender to allow customers to communicate with OneSpan Sign from within their own system via REST API calls.
Event Notification	sender_admin.event_notification	This permission enables a Sender to view their account's Event Notifications interface. Integrators can use this interface to request an automatic notification of events that concern the account.
Data Management	sender_admin.data_management	This permission enables a Sender to specify how long transactions in various states will be retained on a OneSpan Sign server.
Signing Customization	sender_admin.customization	This permission enables a Sender to re-brand the Signer Experience in several powerful ways.
Notary	sender_admin.notary	This permission enables a Sender to enable the IPEN feature on a notary’s account. This feature enables the notary to e-sign and notarize documents in a “notarized transaction”.
Security Settings	sender_admin.security_settings	This permission enables a Sender to specify a password policy for their account.
Account Configuration	sender_admin.self_serve_account_settings	This permission enables a sender to access the Account Configuration page.
Reports	sender_admin.reports	This permission enables a Sender to view the Reports menu in the Navigation Bar, and thus access reports about their account.
Roles	sender_admin.role	This permission enables a Sender to manage the roles associated with their account.
Group Permissions
Group Signing Management	groups.group_signing_management	This permission enables an Account Owner or Manager to manage Groups on their account (Sender UI Email Groups).
Template and Layout Permissions
Template	templates_layouts.templates	This permission allows administrators to add template access permissions to a role. For example, from the OneSpan Sign UI admins can now configure a role so that a user can see the Templates menu, and from there create, update, and delete templates. Integrators using our APIs can define whether a user can create, edit, or delete templates.
Share Template	templates_layouts.share_templates	This permission enables a Sender to make their templates available to other users on their account.
Save Layout		This permission enables a Sender with this permission enabled for their role to create a layout from a transaction they are creating. Note that this permission will override any configurations made in the Designer, meaning that if, for example, a user does not have the Save Layout permission enabled for their role they will not be able to save layouts, even if the Designer has been configured to allow that.
Share Layout	templates_layouts.share_layouts	This permission enables a Sender to make their layouts available to other users on their account.
Apply Layout		This permission enables a Sender with this permission enabled for their role to apply a layout from a transaction they are creating. Note that this permission will override any configurations made in the Designer, meaning that if, for example, a user does not have the Apply Layout permission enabled for their role they will not be able to apply layouts, even if the Designer has been configured to allow that.
Transaction Permissions
Transaction	transaction.transaction	This permission enables a sender to create, view and edit transactions and templates.
Create New Transaction	transaction.transaction_from_scratch	This permission enables a sender to create, view, and edit transactions. This permission does not automatically give the sender the permission to create a transaction from a template.
Create Transaction from Templates Only	transaction.transaction_from_template	This permission enables a sender to create, view, and edit a transaction using templates. This permission does not automatically give the sender permission to create a transaction on their own.
In Person Signing	transaction.in_person	This permission enables a Sender to use the In-Person signing feature on a transaction.
Change Signer Option	transaction.change_signer	This permission enables a signer to delegate their signing responsibilities to another person.
Transaction visibility in delegation	transaction.delegation_visibility	This permission enables a delegate to see all the transactions on the account they have been delegated to manage.

Manage account roles

By default, OneSpan Sign offers the following roles, each with their own default permission sets:

• Administrator: Has full access to the application and its configurations
• Manager: Has full access to the application

  If Enterprise Administration has been enabled for your account a Manager will not be able to assign a delegate for any of their senders.

• Sender: Has limited access to the application
• Notary: Has limited access to the application, with additional notary functions.

These default roles are not customizable, and they cannot be deleted. Account Administrators can nonetheless: (1) create customized roles, assigning a customized set of permissions to each one; (2) make a customized role available within specified accounts.

Should you need to create additional custom roles you can do so using the Java SDK.

Ensure your SDK is version 11.35 or higher.

To create an account role:

	
				//create
				AccountRole accountRole = AccountRoleBuilder.NewAccountRole()
				.WithName("Sales Manager")
				.WithPermissions(new List<String> { "transaction.transaction", "transaction.in_person" })
					.WithDescription("Customized Role for Regional Manager")
					.WithEnabled(true)
					.Build();
					ossClient.AccountService.addAccountRole(accountRole);
					//			
				

As a response, an account role ID formatted in UUID will be returned. Store this ID to a local file because you will need to reference it for additional procedures.

To query a specific account role by its ID:

AccountRole accountRole1 = ossClient.AccountService.getAccountRole("account_role_id");
			

To retrieve a list of all the existing account roles:

List<AccountRole> accountRoles = ossClient.AccountService.getAccountRoles();

To update an account role name, description or associated permissions:

 AccountRole accountRole2 = ossClient.AccountService.getAccountRole("account_role_id");
				accountRole2.Description = "Updated Description";
				accountRole2.Permissions.AddRange(new List<String> { "sender_admin.security_settings", "sender_admin.reports" });
			ossClient.AccountService.updateAccountRole("account_role_id", accountRole2);

To disable an account role:

Instead of directly deleting a role, you can choose to disable it first. Disabling the account role functions the same as the delete operation but leaves you with the option to enable the role again, if needed.

AccountRole accountRole3 = ossClient.AccountService.getAccountRole("account_role_id");
				accountRole3.Enabled = false;
			ossClient.AccountService.updateAccountRole("account_role_id", accountRole3);

To delete an account role:

If you decide not to keep a disabled account role, you can delete the role.

This action is not reversible.

ossClient.AccountService.deleteAccountRole("account_role_id");

To retrieve a list of sender IDs assigned to a role:

List<String> accountRoleUsers = ossClient.AccountService.getAccountRoleUsers("account_role_id");
			Collap

Results

Here is an example of what you can expect to see once you have run your code.

After executing the sample code, you can find your newly-created account roles in your OneSpan Sign account. Navigate to Admin > Roles to see the original and custom account roles.

Assign an account role to a sender

With the account roles set up in your account, the next step is to associate the roles to your existing sender.

To assign an account role to a sender:

List<AccountRole> acountRoles = new ArrayList<>();
acountRoles.add(AccountRoleBuilder.newAccountRole().withId("your_account_role_id1").build());
acountRoles.add(AccountRoleBuilder.newAccountRole().withId("your_account_role_id2").build());
acountRoles.add(AccountRoleBuilder.newAccountRole().withId("your_account_role_id3").build());
UserAccountRole userAccountRole = new UserAccountRole("sender_id","accountId",acountRoles);
userAccountRole = client.getAccountService().assignAccountRoleToUser(userAccountRole.getUserId(),
userAccountRole);

To download the full code sample see our Code Share site.

With the Roles and Permissions feature, admins have more control over their senders’ access permissions. By creating a customized Account Role with a set of permissions and assigning the role to a sender, it determines the actions available to the sender and makes it easy to manage the access rights of a large number of senders without having to change their respective permissions.

Without turning on the Roles and Permissions feature, admins are only able to specify two static role types: “Sender” and “Manager”. This may be insufficient when the number of senders grows and they need access to different elements in the account. Assigning roles and permissions to your senders allows you to control this.

Turn on roles and permissions

By default, the Roles and Permissions feature is disabled, so admins should contact our Support Team to arrange this configuration in the account. Once enabled, the option to configure Roles will appear in the OneSpan Sign Admin menu. For more information, see Managing Roles.

When making API calls with an API Key, OneSpan Sign creates an API Key session if one is not already in use. If an API Key session has already been created, then OneSpan Sign will use the existing session. However, if Roles and Permissions have been cached in this session then any changes that are made will not appear until the session expires. By default, API Key sessions expire after 15 minutes.

Available permissions

With a role-based access model, you can group senders with similar needs into a role. You then grant permissions to the role which determine the pages and actions the senders can access. The following table describes all of the permissions in OneSpan Sign. Note that each permission has a Permission ID which you will use when setting up the roles and permissions for your organization.

If a specific feature is not enabled for an account then the permission associated to that feature is not available. Also, the available permissions may change when new features and releases are rolled out to an account.

When creating custom roles via integration, you must ensure to include the template permission as well and not depend on the existing "Transaction" permission to determine whether templates are allowed to be created/updated/deleted.

Permission	Permission ID	Description
Trust Vault Permissions
No access		This permission denies access to the Trust Vault.
View their own transactions		This permission enables a Sender to view any of their transactions that have been archived to the Trust Vault.
View and delete their own transactions		This permission enables a Sender to view and delete any of their transactions that have been archived to the Trust Vault.
View all transactions		This permission enables a Sender to view all transactions that have been archived to the Trust Vault.
View and delete all transactions		This permission enables a Sender to view and delete all transactions that have been archived to the Trust Vault.
Sender Admin Permissions
Custom Fields	sender_admin.custom_fields	This permission enables a Sender to create and manage Custom Fields.
User Management	sender_admin.users	This permission enables a Sender to manage the users associated with their account.
Subscription account billing details	sender_admin.subscription	This permission enables a Sender to view the Subscription page, which contains billing details for their account.
API Access	sender_admin.api_access	This permission enables a Sender to allow customers to communicate with OneSpan Sign from within their own system via REST API calls.
Event Notification	sender_admin.event_notification	This permission enables a Sender to view their account's Event Notifications interface. Integrators can use this interface to request an automatic notification of events that concern the account.
Data Management	sender_admin.data_management	This permission enables a Sender to specify how long transactions in various states will be retained on a OneSpan Sign server.
Signing Customization	sender_admin.customization	This permission enables a Sender to re-brand the Signer Experience in several powerful ways.
Notary	sender_admin.notary	This permission enables a Sender to enable the IPEN feature on a notary’s account. This feature enables the notary to e-sign and notarize documents in a “notarized transaction”.
Security Settings	sender_admin.security_settings	This permission enables a Sender to specify a password policy for their account.
Account Configuration	sender_admin.self_serve_account_settings	This permission enables a sender to access the Account Configuration page.
Reports	sender_admin.reports	This permission enables a Sender to view the Reports menu in the Navigation Bar, and thus access reports about their account.
Roles	sender_admin.role	This permission enables a Sender to manage the roles associated with their account.
Group Permissions
Group Signing Management	groups.group_signing_management	This permission enables an Account Owner or Manager to manage Groups on their account (Sender UI Email Groups).
Template and Layout Permissions
Template	templates_layouts.templates	This permission allows administrators to add template access permissions to a role. For example, from the OneSpan Sign UI admins can now configure a role so that a user can see the Templates menu, and from there create, update, and delete templates. Integrators using our APIs can define whether a user can create, edit, or delete templates.
Share Template	templates_layouts.share_templates	This permission enables a Sender to make their templates available to other users on their account.
Save Layout		This permission enables a Sender with this permission enabled for their role to create a layout from a transaction they are creating. Note that this permission will override any configurations made in the Designer, meaning that if, for example, a user does not have the Save Layout permission enabled for their role they will not be able to save layouts, even if the Designer has been configured to allow that.
Share Layout	templates_layouts.share_layouts	This permission enables a Sender to make their layouts available to other users on their account.
Apply Layout		This permission enables a Sender with this permission enabled for their role to apply a layout from a transaction they are creating. Note that this permission will override any configurations made in the Designer, meaning that if, for example, a user does not have the Apply Layout permission enabled for their role they will not be able to apply layouts, even if the Designer has been configured to allow that.
Transaction Permissions
Transaction	transaction.transaction	This permission enables a sender to create, view and edit transactions and templates.
Create New Transaction	transaction.transaction_from_scratch	This permission enables a sender to create, view, and edit transactions. This permission does not automatically give the sender the permission to create a transaction from a template.
Create Transaction from Templates Only	transaction.transaction_from_template	This permission enables a sender to create, view, and edit a transaction using templates. This permission does not automatically give the sender permission to create a transaction on their own.
In Person Signing	transaction.in_person	This permission enables a Sender to use the In-Person signing feature on a transaction.
Change Signer Option	transaction.change_signer	This permission enables a signer to delegate their signing responsibilities to another person.
Transaction visibility in delegation	transaction.delegation_visibility	This permission enables a delegate to see all the transactions on the account they have been delegated to manage.

Manage account roles

By default, OneSpan Sign offers the following roles, each with their own default permission sets:

• Administrator: Has full access to the application and its configurations
• Manager: Has full access to the application

  If Enterprise Administration has been enabled for your account a Manager will not be able to assign a delegate for any of their senders.

• Sender: Has limited access to the application
• Notary: Has limited access to the application, with additional notary functions.

These default roles are not customizable, and they cannot be deleted. Account Administrators can nonetheless: (1) create customized roles, assigning a customized set of permissions to each one; (2) make a customized role available within specified accounts.

Should you need to create additional custom roles, you can do so using the RESTful API.

To create an account role:

HTTP Request

POST /api/account/roles

HTTP Headers

Authorization: Basic {your_api_key} 
Content-Type: application/json 
Accept: application/json 

Example Payload

 {
	"name": "Regional Manager", 
	"enabled": true, 
	"description": "Customized Role for Regional Manager",
	"permissions": 
		["transaction.transaction",
		 "transaction.in_person",
		  ......]
 }

As a response, an account role ID formatted in UUID will be returned. Store this ID to a local file because you will need to reference it for additional procedures.

To query a specific account role by its ID, or to retrieve a list of all the existing account roles:

HTTP Request

GET /api/account/roles 
GET /api/account/roles/{accountRoleId} 

HTTP Headers

Authorization: Basic {your_api_key}			
Accept: application/json 

To update an account role name, description or associated permissions:

HTTP Request

PUT /api/account/roles/{accountRoleId} 

HTTP Headers

Authorization: Basic {your_api_key} 
Content-Type: application/json 
Accept: application/json 

Example Payload

 {
	"name": "Updated Account Role Name",  
	"enabled": true, 
  
	"description": "Updated Description", 
  
	"permissions": 
		["sender_admin.security_settings",     
	 	 "sender_admin.reports"
	 	 ...... ]
 }

To disable an account role:

Instead of directly deleting a role, you can choose to disable it first. Disabling the account role functions the same as the delete operation but leaves you with the option to enable the role again, if needed.

HTTP Request

PUT /api/account/roles/{accountRoleId} 

HTTP Headers

Authorization: Basic {your_api_key}			
Content-Type: application/json			
Accept: application/json 

Example Payload

{"enabled":false} 

To delete an account role:

If you decide not to keep a disabled account role, you can delete the role.

This action is not reversible.

HTTP Request

DELETE /api/account/roles/{accountRoleId} 

HTTP Headers

Authorization: Basic {your_api_key} 
Assign Role to Sender 

Assign an account role to a sender

With the account roles set up in your account, the next step is to associate the roles to your existing sender with this API.

To assign an account role to a sender:

HTTP Request

POST /api/account/senders/{senderId}/roles 

HTTP Headers

Authorization: Basic {your_api_key} 
Content-Type: application/json 
Accept: application/json 

Example Payload

 {
	"accountId" : "Us1VqQw3r3kN",
	"accountRoles": [ {"id": "owner"}, {"id": "member"}]
 }

 

• For an "accountRoles" array, you must provide the account role ID for each node.

To retrieve a list of sender IDs assigned to a role:

HTTP Request

GET /api/account/roles/{accountRoleId}/users 

HTTP Headers

Authorization: Basic {your_api_key} 
Accept: application/json 

Results

Here is an example of what you can expect to see once you have run your code.

After executing the sample code, you can find your newly-created account roles in your OneSpan Sign account. Navigate to Admin > Roles to see the original and custom account roles.

You can confirm the sender is associated with the account role by navigating to Admin > Users to locate the sender's profile.